Getting Started & Isolated Build Tools

Welcome to the setup and getting started guide for Pepvoid Builder. This document describes the isolated host-tool architecture, system requirements, and build walkthroughs.

1. Isolated Host Toolchain

Pepvoid Builder isolates much of the target build toolchain, but it is not a hermetic build service. The host still needs Linux, Python, system utilities, network access for uncached packages, and the permissions required by the selected execution mode.

How Isolation Works:

Static build tools: In real mode, ToolchainManager caches static XBPS binaries under the checkout’s tools/ directory and copies them into the current build’s isolated workdir/<architecture>/<build-id>/build_host/tools/ directory. On non-root x86_64 runs, it can download the pinned PRoot release; root runs use native chroot instead.
Host tools: The CI environment installs mtools, dosfstools, xorriso, squashfs-tools, and gettext in addition to Python dependencies. Other formats or hooks may require additional tools. Check the pre-build diagnostics on your host.
Execution modes: Real builds use native chroot when run with sufficient privileges. Non-root execution uses proot where supported; platform and host constraints still apply.
Host compatibility: The project targets Linux hosts. Compatibility with a distribution does not imply that every build mode works identically on every version or architecture.

2. Requirements

Host Requirements

Python: Python 3.9 or higher.
Disk Space: 10 GB free space on a local Linux filesystem (EXT4, Btrfs, XFS).
RAM: 4 GB minimum.
Build tools: mtools, dosfstools, xorriso, squashfs-tools, and gettext for the CI-validated workflows. Some build formats and custom hooks need further tools.

Install the builder

Run the builder from a complete source checkout; a standalone wheel does not include its configuration and asset tree. From the repository root, install it in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
void-builder --check

Install test and lint tools as well when contributing:

python -m pip install -e '.[dev]'

3. Automatic Static Toolchain Resolution

When ToolchainManager.setup() executes, it automatically manages the toolchain:

tools/                         # persistent download cache in the checkout
├── proot                              # User-space chroot/emulation binary
└── usr/
    └── bin/
        ├── xbps-install.static        # Static XBPS installer binary
        ├── xbps-rindex.static         # Static XBPS repository indexer
        └── xbps-query.static          # Static XBPS query tool

Missing tools are fetched from the configured upstream HTTPS endpoints; --update-toolchain forces a refresh. Static XBPS archives are checked against the upstream sha256sums.txt manifest before extraction. The manifest is fetched from the same mirror over HTTPS and is not independently signed, so this detects transfer corruption but does not provide an independent authenticity guarantee. PRoot is restricted to x86_64, pinned to release v5.5.0, and checked against the SHA-256 digest published with its release assets. A newer PRoot release requires updating the version and digest together. Other host architectures need a native PRoot at tools/proot and a matching SHA-256 digest in tools/proot.sha256; root builds use native chroot.

4. Cross-Architecture Host Helper (Optional)

When cross-building for foreign CPU architectures (e.g. building an aarch64 or rpi image on an x86_64 host), the helper script setup_host_build_env.sh can optionally configure kernel binfmt_misc user-mode emulators:

sudo ./setup_host_build_env.sh

5. Verification & First Build Walkthrough

Step 1: Configuration Validation

Audit all JSON configuration profiles and dynamic package rules without building:

python3 cli.py --check

Outputs:

🔍 Validating configuration for target architecture 'x86_64'...
2026-07-22 11:40:00 - ConfigLoader - INFO - Starting configuration assembly for x86_64...
2026-07-22 11:40:00 - ConfigLoader - INFO - Applied dynamic package rules from package_rules.json successfully.
2026-07-22 11:40:00 - ConfigLoader - INFO - Configuration assembly completed successfully.
✅ Configuration is VALID!
Summary:
  - Target Architecture: x86_64
  - Desktop Profile:     base
  - Total Packages:      136
  - Enabled Services:    dbus, NetworkManager, polkitd, bluetoothd, cupsd, avahi-daemon, sshd, chronyd, alsa, acpid, elogind, wpa_supplicant

Step 2: Non-Root Simulation (Mock Mode)

Simulate building an x86_64 ISO with XFCE desktop environment:

python3 cli.py x86_64 -d xfce --mode mock

This verifies the build tree, packages list, and bootloader configuration without needing root privileges.

Step 3: Production Real ISO Build

Run a real build to create the image. It downloads packages and writes the artifact to the selected output path:

sudo python3 cli.py x86_64 --preset desktop-xfce --mode real --output output/pepvoid-xfce.iso